Welcome to the world of DukeEdit, the only (so far as I know) map editing software for Duke Nukem 3D available on the Macintosh!
If you're like me, you're thinking, "Why should I read this tutorial? tutorials are for woosies who can't figure things out or for programs with cruddy user interfaces. Either way, I'm not reading it."
Fine. Go on and run DukeEdit without using the tutorial. I wish you luck, but I hope you don't need it.
Now, for those of you still reading this, we can continue.
I hope in this tutorial to guide you through your first encounter with DukeEdit, show you some of the features, and get you started making your own maps and looking at maps made by others, even the maps made by the good folks at 3D Realms. You might find it useful to print this tutorial out before continuing.
I am naturally assuming you have managed to un-binhex and un-stuff the application file, since otherwise you couldn't possibly be reading this. In case you're wondering, there are no restrictions on where the DukeEdit application resides. You can put it in with the Duke Nukem program or in its own folder or wherever, and it will still run fine. On my Mac, it's even on a different disk drive.
Start off by double-clicking the application. The first thing you will see is a somewhat less-than-friendly dialog box advising you that you need to have Duke Nukem 3D installed to use this product. This is not really much of a restriction, since DukeEdit is pretty useless without Duke Nukem anyway. Click 'continue' and a standard file open dialog pops up. You will need to locate the file 'Duke3D Group', which is the file containing almost all the data used by the Duke Nukem application. DukeEdit uses this data to make available to the user lists of sprites, level maps (like "Hollywood Holocaust"), and pictures of textures which you will find to be indispensible when making maps of your own.
If you are successful in locating this file and clicking the 'open' button, nothing seems to happen! Congratulations! You are ready to begin using DukeEdit. If anything went wrong, you're probably staring at an alert box which, when dismissed, will drop you back in the Finder where you can start this process over again.
If you have gotten this far successfully, you will be wondering what all these windows mean. These are floating windows and they are the tools you will use to create, edit or simply examine maps. In the upper left corner you will find the DukeEdit toolbar, which, like most toolbars, allows you to do basic operations like Open, New, Save, as well as other functions like going into Draw mode, Magnify mode or Navigate mode. In the upper right corner you will find two overlapping windows. Ignore the one titled 'Stratum' for now. The one titled 'Info' is very important; it provides you with quick and basic information about sprites and sectors, along with tips and messages. Moving the mouse cursor over most of the windows or controls in DukeEdit will cause the Info window to display a tip, like "Create a new map", when you move the mouse cursor over the upper-left button on the toolbar. The Info window is also where to look if you hear a beep; there will probably be some text at the bottom of the window, displayed in red, telling you why the program beeped at you. The last window is in the lower right corner of the display, and is titled 'Sprites'. You will use this window to create new sprites and drop them on your maps. The pop-up menu at the top of the Sprite window contains some pre-canned sprites you may find useful.
Enough of this already, we want to look at maps! We will start out by looking at "Hollywood Holocaust", a map every Duker should be familiar with. Click the 'open' button on the toolbar (or use command-O or 'Open' from the File menu) and up pops a standard open file dialog box. Locate the same file you found a few paragraphs up, 'Duke3D Group', and click OK. Oh Joy, Another Dialog! But this one is a bit more interesting than the rest. It contains a list box with the names of all the maps in the Duke3D Group file (in the order they appear in the file, in case you're wondering). Scroll through the list box and choose 'E1L1 - Hollywood Holocaust', click OK, and if everything is working as it should, you should be looking at that map.
Don't worry about corrupting the Duke3D Group file. DukeEdit never, ever, writes to that file (unless you do something unwise like create a map, name it 'Duke3D Group', and place it in the Duke Files folder). There are only two kinds of files DukeEdit creates; one is the preferences file in the usual place preferences are supposed to go, and the other is a map file. Currently, the E1L1 map you are looking at is only in memory, it hasn't been saved to disk yet, and if you try to save it you will be shown a standard save file dialog box. Don't overwrite the Duke3D Group file, or you will have to reinstall Duke Nukem 3D (also, DukeEdit will become very confused)!
Anyway, looking at Hollywood Holocaust, you will notice a few things. Some lines are black, some are gray, and some are magenta. What do they mean? Black lines are one-sided lines, i.e. lines that separate solid rock from the inside of 'rooms'. Gray lines are two-sided lines, which Duke could cross provided the floors of the sectors on each side of the line are roughly the same height. Magenta lines show you sectors defined to be 'secret' areas, something you will find quite useful, especially if you are like me and can't quite seem to find all the secret areas on each level.
Click on the lower-left button of the toolbar (it looks like a magnifying glass), and position the mouse cursor over the map. It should change to a little magnifying glass with a dotted '+' in the middle. Clicking somewhere on the map now will cause the map to magnify by an order of two. Notice when you do this that the name of the window changes from 'E1L1.MAP (1x)' to 'E1L1.MAP (2x)'. Just like other applications you've probably used, the stuff in parentheses is not part of the filename, but simply provides you with information on what level of magnification is currently being used. Clicking repeatedly will continue magnifying by orders of two, up to 256x, at which point the mouse cursor becomes a magnifying glass with no '+' in the middle, indicating that no more magnification is possible.
To demagnify the map, hold down the 'option' key when you click. Notice the mouse cursor changes to a magnifying glass with a dotted '-' in the middle; again a visual cue to what you can do.
At any point in time you can move the map around using the scroll bars, but a much easier way to do this is to hold down the 'control' key. Notice the mouse cursor changes to an open hand while the cursor is over the map and the control key is down. If you click on the map now and move the mouse while the button is down, the cursor changes to a closed hand and you will drag the map around with the mouse cursor as it is moved. You will find this short-cut useful when trying to line up a sector 'just so' for editing. You don't have to use the control key, of course, you can go into 'Navigate' mode by clicking on the lower-right button on the toolbar and perform the same functions.
By the way, if you ever get 'lost' on the map -- all you can seem to find is empty white space -- go up to the Edit menu and select 'Recenter', and presto! You are back in 1x with the map centered on the screen.
Now, use the magnify tool to blow up (so to speak) the sectors in the north-west (or upper-left) portion of E1L1.MAP. You will probably identify this area as the top of the building where Duke starts out in Hollywood Holocaust, and indeed that is exacty what it is. You should notice a five-pointed star on the rooftop. This marks the location where Duke starts out when the level begins, and this can be changed using the Duke tool, which is selected using the button on the toolbar bearing our hero's image. If you select that now, you will find that the mouse cursor changes to a crosshair when over the map, allowing for fine placement. Pressing down on the mouse button causes the five-point star to move to the new location under the mouse, and by holding down the mouse button and dragging it away you will drag a line along with the mouse. Let go of the mouse when the line points in the direction you want Duke facing when he begins the level. It's that simple. One caveat, though -- if Duke doesn't start out in a valid sector, attempting to play the map will result in immediate death by squashing.
All the little 'diamonds' on the map are sprites. Select 'sprite' mode on the toolbar (it's the button with a little diamond in it) and move the cursor over a sprite. No need to click it just yet. Notice that the sprite turns red, a process I call 'hiliting', and if you're really observant you will notice that some text has appeared in the Info window (remember the Info window?) indicating the sprite number (not too useful), the "tag" values -- don't worry about them now -- and just below that a word in all capital letters indicating what 3D Realms calls the sprite (or else the phrase 'not named' in lowercase if 3D Realms did not assign this kind of sprite a name), along with the texture number in parentheses. Note that the 'sprite number' is a fairly arbitrary number indicating which of the sprites it is on the map (for example it may be sprite 112 of the the 644 sprites on E1L1), while the texture number is a number that identifies what kind of sprite it is (for example texture number 28 is the familiar shotgun sprite).
Sprites are used for all kinds of things on Duke Nukem maps, not just stuff you can pick up, look at or blow away; they are used to set up special effects too. But that is for another time.
Clicking on a sprite while in sprite mode causes it to turn blue, which I call 'selecting'. A selected sprite can be deleted using the 'delete' key or 'Clear' or 'Cut' from the Edit Menu. Go ahead and delete one, just for the fun of it. Now, to get it back, press command-Z or choose 'Undo' from the Edit menu, and it should reappear. Undo should work for any destructive act you might accidentally perform, making it a useful feature you will probably use many times.
Double-clicking a sprite leads to the sprite dialog, which is used to change the properties of a sprite, such as its texture, shading, palette, direction, tag values, flags, and so on. There is a tremendous learning curve here; see the end of this document for references to help you out with these things, they are well beyond the scope of this tutorial.
Similar features are available in 'sector' mode (the button on the toolbar with the closed polygon in it). Moving the cursor over a sector hilites the sector and puts text in the info window describing some basic information about the sector, clicking on the sector selects it so you can delete it, and undo can bring it back if you delete it accidentally. Double-clicking on a sector, however, brings up a whole new kind of window, the 'Sector window', which will have a title like 'E1L1.MAP: Sector 389'. Sector windows have a diagram of the sector, some info about the sector on the right side of the window, and five buttons along the top. Notice that walls again are either black or gray, depending on whether they are one-sided or two-sided, and that one of the walls of the sector is colored differently from the rest. This is the 'first wall' of the sector, which is used to define the direction sloped sectors slope. They slope away from the first wall, but again going any further on this subject is beyond the scope of this tutorial.
Double-clicking on a wall brings up the wall dialog, which, like the sprite dialog, is used to change the properites of a wall. Again, details of all the items in this dialog is too big a digression for this tutorial.
The button in the sector window marked 'Edit Sector' brings up a dialog box similar in style to the sprite dialog box described above. The 'All Walls' button allows you to change all the walls of a sector at once, which is a feature you will want to use often when making your own maps, since it is tedious to change your sector's walls one-at-a-time. The 'First Wall' button doesn't become enabled until you click on one of the walls of the sector (i.e. 'hilite' it), and it makes the selected wall the first wall of the sector. The 'Alignment' button gives you the ability to align the textures in your sector or level, as well as set the slopes of floors and ceilings so they line up exactly with neighboring sectors. It too doesn't become enabled until you select a wall, and the sloping functions of the alignment dialog aren't enabled unless you select a two-sided wall other than the first wall. The 'Other Sector' button is also enabled only when a two-sided wall is selected, and will call into existence yet another sector window for the sector on the other side of the selected wall.
Use 'draw' mode (the button on the toolbar with the incomplete polygon on it) to draw new sectors on the map, or to split existing sectors into two pieces.
Now, close the E1L1 map by any of the standard methods (the close box on the window, command-W, or use 'Close' in the File menu). Select 'New' using the toolbar, command-N, or 'New' in the File menu, and we will begin to make a small map.
Once you are in draw mode, click once on an open area to begin drawing a new sector, and then move the cursor to a different spot. Notice that a line follows the cursor and turns brown when you click that second time. This indicates the first wall of your new sector has been layed down (and yes, it is the 'first wall' mentioned above). Moving the cursor again causes a new line to stream away from the second point, and clicking again lays down the second wall of your new sector in brown. Continue in this manner until you are done drawing the sector, an event which you cause when you come all the way around and click on the original first point (which should have a small brown square around it). Once this is done no more lines stream away from the cursor as it moves, the lines which used to be brown are now black, and the message 'Sector drawing completed' appears in the info window. You will note that the count of sectors and walls has changed in the info window as well, to reflect the new drawing you made.
DukeEdit will not allow you to draw an illegal sector; for example one that crosses itself like a figure-8. An attempt to make such a drawing will result in an alert, and when you dismiss the alert the illegal drawing will disappear.
Now, make sure that Duke is inside the sector (see above if you forgot how to do this), and save the map. Give it a name with the letters ".map" on the end (such as "test.map") and save it away. Congratulations, you have made your first map with DukeEdit!
To play the map, you will need to have the commercial version of Duke Nukem 3D. Switch to the Finder, and simply drag the map icon and drop it onto the Duke Nukem application. After all the splash screens, you should see the words "Entering User Map" and a few seconds later, you should be in your new map. Yahoo!
Anyway, back to DukeEdit.
At any time while drawing, you can use the 'delete' key to back up one point in the drawing, so if you have already drawn five points (making four walls) and hit the 'delete' key, the fifth point disappears and only four points (and thus three walls) remain, and you can continue drawing from there. Hitting 'delete' multiple times successively removes one point until only one point remains. Hitting 'delete' again when there is only one point left gets you completely out of drawing you started and allows the mouse to be moved without a trailing line. However, once a drawing is completed (you have come all the way around and clicked on the original point), backups are no longer able to be performed. Undo is available, but it will erase the sector you just made, and you will have to start all over again. Perhaps not as user-friendly as you'd like (or as I'd like), but that's the way it is right now.
At any time during the drawing process the full functions of DukeEdit are available. You can adjust scrollbars, use the 'control' key to navigate around the map, use the menu bars, just about anything short of closing the map, and it should work without messing up your drawing. Pretty neat, huh.
As you are drawing, you will probably want to connect up to existing sectors. When the mouse cursor comes near an existing sector's wall (or vertex), the wall (or vertex) will hilite -- turn red -- indicating that clicking there will connect the sector you are drawing to the wall (or vertex). This sounds a bit confusing, perhaps, but trying it out will clear things up pretty quickly. A note on this feature: in this release of DukeEdit, drawings that are to connect to an existing sector must begin on a sector. If you begin a drawing out in 'free space', no lines or vertices will hilite as you pass over them, which indicates that connecting up will not happen automatically. I have not encountered a situation where this limitation cannot be 'worked-around', but nonetheless I hope to have this 'feature' fixed in a future update.
Splitting a sector is straightforward. While in Draw mode, move the mouse cursor to a wall of the sector you wish to split into two pieces, click on the wall and draw a line (or lines) as above to cut the sector into two pieces. As soon as you click on the wall of the sector again, the drawing will complete (turn from brown to black) and the message 'Sector split' will appear in the Info window.
There will be times when you will want to create columns inside sectors, or create sectors inside of other sectors. These are accomplished fairly easily. To create a column (i.e. an area of solid rock inside a sector) simply move the mouse cursor to the appropriate place inside the sector and draw the outline of the area you wish to 'carve out' of the sector. When you come around full-circle, the new drawing will turn from brown to black and the words 'Carved an area out of a sector' will appear in the info window. That's it. To create a sector inside an existing sector (also known as a 'child' sector inside its 'parent' sector), first create a 'carve-out' shaped like the child sector you want to make, then double-click inside the carve-out. A dialog will ask you if you want to make the carve-out into a child sector; click OK and you've got yourself a child sector. To avoid the dialog, you can hold down the 'option' key when you double-click and the carve-out will become a child sector with no dialog, but an informational message will appear in the info window.
Joining two neighboring sectors into a single sector is done in sector mode. Select the two sectors (using shift-click in the standard Mac way) and then choose 'Join Sectors' in the Edit dialog and the sectors should join and a message should appear in the Info window. Actually, more than two sectors can be so joined, so long as they all connect together. Just keep shift-clicking until all the sectors you wish to join are selected and choose 'Join Sectors'.
The two remaining modes are 'Split Wall' and 'Move Stuff'. Split Wall mode is used to insert a vertex into an existing wall, and is very rarely needed; but since some map designers really like it, I included it. The Move Stuff mode, however, is useful for everyone. Click on any sprite and drag it to a new location. Click on a vertex and drag it around, and all the walls connected to that vertex move with it. Drag a wall and the whole wall moves, as well as all walls connected to it! One note: when dragging a vertex around, sometimes a wall will disappear from the map when you drop the vertex. Don't worry, the wall is still there. Select 'Redraw Map' from the edit window or just move the cursor over the spot where the wall used to be and it will still hilite. There is a little innocuous bug in there I need to squash, but nothing to worry about.
Moving sectors has not yet been implemented, as well as cutting, copying and pasting anything in the standard Mac way. These are important features to have, especially when creating teleporters, water/underwater areas, elevators and the like, but I just haven't gotten around to it yet. I promise I will sometime Real Soon Now.
Creating new sprites is pretty easy. Check out the Sprites window. Using the pop-up menu at the top of the window, pick a set of sprites that looks like it contains what you want; e.g. pick 'weapons' if you want to create a new shotgun sprite. The ten sprites in the window should change to show the ten pre-canned sprites in the sprite set. Find the sprite you are interested in (hopefully it is there), and move the mouse cursor over the 'pot' icon to the left of the sprite name, and you should see the mouse cursor change to a hand that looks like it is about to pick something up. Click in the 'pot' and the mouse cursor changes to a large diamond with a cross-hair inside it. Hold the mouse button down and drag the sprite to your map, dropping it in the place where you want it, right in the middle of the cross-hair. When you drop the sprite, the cursor 'obscures' -- i.e. disappears until you move it again -- so that you can see exactly where you dropped the new sprite.
If the sprite you want is not in any of the sprite sets, don't despair. Click on any of the ten 'Edit' buttons, and you will be presented with a sprite dialog box. Click on Choose Texture and start looking through all the textures until you find the one you want. You will probably want to change a few of the other things in the dialog when you get used to how Duke Nukem works, but for now clicking on OK will put the sprite of your choice in the Sprites window so you can drag as many of them as you like to your map (up to the Duke Nukem limit of 4096 total sprites on a single level).
You will probably want to create your own sprite sets. This is really pretty easy. Just edit the sprites in the sprite window until they look the way you want them, and click on the 'Add' button. Fill in the name you want to give the sprite set, click 'OK' and, voila! You have your own sprite set! It will appear in the pop-up menu right below the separator line below the pre-canned sprite sets, and will still be there even if you quit the program and launch it again later. If you decide you are sick of one of your sprite sets, you can delete it using the 'Del' button.
There are a few other things I should mention.
There is a grid feature, which is selected using the Grid menu. When enabled, this forces all drawing, moving, Duke placement and sprite placement to align on grid boundaries, so for example if you set 'Grid' to 64x64, all X and Y values will be forced to be multiples of 64.
If the grid granularity is coarse enough to be seen on the map, an actual grid will be drawn on the window, but even if no grid can be seen the X and Y alignment is still enforced. You can easily set and reset the 'Snap-to-grid' feature using the command-G key combination, or the 'Grid' menu.
When it comes to the 'Undo' feature, there are two options available to you, selectable via Preferences. You can choose to implement undo eight changes deep (in a 'wrap-around' fashion) by using disk-based save buffers, or you can choose to implement a simple one-change-deep undo feature using a RAM buffer. The advantage to the one-deep buffer is speed, and this is how I configure DukeEdit for myself, even though I have a very fast system.
One of the very confusing things about Duke Nukem map files is that the Z axis is inverted. Very large positive Z values result in sprites, floors and ceilings that are very low, while very large negative Z values result in things way high up in the air.
One of the things I mentioned right at the top is the Stratum window. I was originally going to call it the Layer window but I thought that might be confused with layer implementations in other well-known Mac programs, so I gave it the name 'Stratum'. This feature allows you to edit sectors that are physically above other sectors, without having to see the sector you are uninterested in. For example, if you are interested in working on a sector whose floor is at, say -10000 Duke Units, but there is a sector below whose ceiling is at, say, -5000 Duke Units (hence below the first sector), you could set the Stratum 'Bot Z' value to, say, -7000 (leaving the 'Top Z' value at -verylarge) and the lower sector would temporarily disappear from the map. It's still there, of course, but it's just not drawn. This can make editing such sectors much less confusing.
Apparently Duke Nukem will ignore any map file whose name doesn't end in the letters 'MAP'.
Remember this when you save your work; DukeEdit will not warn you. Duke Nukem will ignore the map file and launch just as if you had double-clicked the application, which may confuse you. If you are having troubles getting maps to run, this may be the problem.
Saved map files that you create are DukeEdit files, and will have icons that look like documents with 'Egg' on them (those nasty eggs that the slimers come out of). You should be able to drop the file icon on the Duke Nukem application when you want to try out your map. If you encounter any trouble doing this, you probably only need to rebuild your desktop, but a simpler solution is to use the type conversion program packaged with Duke Nukem; it will change the file type and creator of your map file so that the Duke Nukem application can recognize the map files. DukeEdit will still recognise the map file, but you will have to drop the icon on the DukeEdit application or open the map file from within the DukeEdit application.
'Open', 'Close', and 'New' work just like you'd expect them to. Closing a map window will also close any associated Sector windows.
The Toolbar, Info, Stratum and Sprite windows can be closed to unclutter the screen, and brought back at any time by using the Window menu.
One time-honored Mac feature that is not yet implemented in DukeEdit is autoscrolling. For example, if you start a drawing and move the cursor off the screen, you will probably expect the map to start scrolling automatically so you can get to the part of the map that's currently off the screen. Well, this doesn't work in this version. Soon, soon. And don't forget, you can still use the scroll bars and the 'Navigate' mode to move around -- the drawing will not be lost, even if you change out of draw mode (for example, into magnify or navigate mode) and then back in again. You will find the drawing right where you left it. So the lack of an autoscrolling capability is not really all that critical, just un-Mac-like.
Some of the maps in the Duke3D Group file have problems. For example, "E1L4 -- Toxic Dump", has two sprites outside of any sector. Just sitting there in solid rock. If you have auto error checking enabled in your preferences and you open this map file, you will get two alerts indicating the problem and the sprite number of the errant sprite. There is nothing wrong with DukeEdit; the problem is a very minor one with the map file. I just wanted you to know in case you see something like this happen. You might also see things like this is user maps you find on the Internet or distributed on CD ROMs. DukeEdit won't allow such things to occur when you make maps.
Before you attempt any serious mapmaking, I strongly suggest you obtain some documentation on Duke Nukem maps. There is some documentation that comes with the game itself, but for better and more complete documentation I recommend either of the following:
1. The Duke Nukem 3D Level Design Handbook, by Matt Tagliaferri, which is available in nearly every decent bookstore. The only complaint I have about this book is that it has no index, so you have to search around a bit to find what you need.
2. The Map Editing FAQ 1.3 available online at www.dukeworld.com. In fact, this URL is a great place to find all kinds of information on Duke Nukem, including some great levels, and even some 'Total Conversions' where people have made completely new sounds, artwork and levels.
Bear in mind, of course, that these references are meant to be companions to BUILD, the DOS-based program the 3D Realms people used to make their own levels, and will not be tailored to DukeEdit. You will probably have to do some investigative work on your own to make things work, or if you want, you can drop me a line and I'll try to get back to you. Be advised that it might take a while; I have a day job.
Good Luck,
John Inman, 7/29/97
jcinman@compuserve.com
Appendix A:
Upgrades to come, *not* in order of importance, but in a randomly chosen order:
1. Printing support.
2. Support for third-party group files (i.e. Total Conversions).
3. More texture alignment helpers (graphical presentation of wall textures in relation to neighboring wall textures, for example).
4. Improved palette pop-ups for sprites, walls, sectors.
5. Some sort of help or guide (beyond info window).
6. More tool windows, patterned loosely after the sprite window, that let you drag and drop wall and sector prototypes onto the map (i.e. an existing wall would be changed to match the prototype wall you create in the wall window, similarly for sectors).
7. Ability to launch Duke Nukem and play the map from within DukeEdit.
8. Save document-specific DukeEdit settings in map file resource fork.
9. Outer loop needn't be first loop in sector -- remove assumption from code.
10. Cut, Copy, Paste ability for sectors, along with requisite dragging and dropping of sectors.
11. Sprite histogram; i.e. a way to determine which sprites appear in a map and with what frequency.
12. Texture inspection window; i.e. a relatively large window that will permit the user to get a better view of the texture. Some beta testers complained that the textures were too small to see properly.
13. Sizing sprites. Currently the only way to make sprites larger or smaller is by using the xrepeat and yrepeat fields of the sprite window, which is quite non-intuitive. Incidentally, larger repeats make larger sprites. I just thought you'd like to know.
14. Autoscrolling during draw and move procedures.
15. Disappearing walls during vertex moves (cosmetic error only; the wall is still there).
None of these upgrades are guaranteed; I reserve the right to leave them unimplemented if I so desire. Do not make purchasing decisions for this product (DukeEdit) based on planned upgrades.
